Description

New core rule RenameDeprecatedMethodCallRector. It looks for method calls (MethodCall, StaticCall) where the called method carries a @deprecated annotation, infers a simple replacement method name from the docblock, and renames the call.

Example

Given a class whose method is @deprecated with a replacement hint:

final class SomeApiClient
{
    /**
     * @deprecated since 2.0, use fetchData() instead
     */
    public function getData(): array
    {
        return $this->fetchData();
    }

    public function fetchData(): array
    {
        return [];
    }
}

the rule rewrites calls to the deprecated method:

-$someApiClient->getData();
+$someApiClient->fetchData();

The same applies to static calls and the replaced by newMethod() / {@see newMethod()} docblock forms.

How it works

1. Resolves the called method's reflection via ReflectionResolver.
2. Hands the reflection to DeprecatedMethodCallReplacementResolver, which:
   • skips unless isDeprecated()->yes();
   • parses getDeprecatedDescription() for a replacement name in three common forms:
     • use newMethod() instead
     • replaced by newMethod()
     • {@see newMethod()}
   • Safety guard: only returns a name if the suggested method actually exists on the same declaring class, and is not itself deprecated (avoids dead-end renames).
3. If a replacement name comes back, the call's method name is swapped.

Scope / limitations (intentional for this first cut)

• Same-class method rename only; cross-class Other::newMethod() suggestions are skipped.
• NullsafeMethodCall not handled (not yet supported by ReflectionResolver).
• A standalone sibling @see tag (outside the @deprecated text) is not read; only inline {@see ...}.
• Registered in the rule's test config only, not wired into any set.

Tests

6 rule fixtures (use-instead / replaced-by / {@see} / static call + 2 skips) backed by a Source/SomeApiClient fixture, plus a dedicated unit test for DeprecatedMethodCallReplacementResolver covering each docblock form and every bail-out path. ECS, PHPStan level 8, and Rector all pass on the new code.